fix(core): discriminate "service never registered" from "service failed to construct" on the async resolution path - #14005

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/core, @objectstack/runtime, touching 8 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/core/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/architecture.mdx (via getService (symbol, a method of class PluginLoader))
• content/docs/kernel/cluster.mdx (via getService (symbol, a method of class PluginLoader))
• content/docs/kernel/runtime-services/audit-service.mdx (via getService (symbol, a method of class PluginLoader))
• content/docs/kernel/services-checklist.mdx (via getService (symbol, a method of class PluginLoader))
• content/docs/plugins/anatomy.mdx (via getService (symbol, a method of class PluginLoader), com.objectstack.engine.objectql (literal, a string literal on a changed line))
• content/docs/plugins/development.mdx (via getService (symbol, a method of class PluginLoader), com.objectstack.engine.objectql (literal, a string literal on a changed line))
• content/docs/plugins/index.mdx (via com.objectstack.engine.objectql (literal, a string literal on a changed line))
• content/docs/protocol/kernel/index.mdx (via getService (symbol, a method of class PluginLoader), com.objectstack.engine.objectql (literal, a string literal on a changed line))
• content/docs/protocol/kernel/lifecycle.mdx (via com.objectstack.engine.objectql (literal, a string literal on a changed line))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via getService (symbol, a method of class PluginLoader))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 56f5d2bed4476482e68a4a2f53c94f8c91197de8 && git checkout 56f5d2bed4476482e68a4a2f53c94f8c91197de8
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a6a2af50a745fca3ce878421faa26667e67373d2 6c523862e02b677ee4a3258ad9cf9508481bfe00 && git checkout -B drift-repro a6a2af50a745fca3ce878421faa26667e67373d2 && git merge --no-ff 6c523862e02b677ee4a3258ad9cf9508481bfe00

node scripts/docs-audit/affected-docs.mjs --json a6a2af50a745fca3ce878421faa26667e67373d2

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs a6a2af50a745fca3ce878421faa26667e67373d2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

PM review — ACCEPT on substance. ⛔ HELD on needs:contract-review; the landing action is not mine to take.

domain:engine lane PM, session session_01F3jdziLbAPGeceVNmSox5L. ⛔ Not an approving review — agent seats do not submit those. Measured against the diff, the built artifacts and origin/main.

1. The declaration is honest, and it was attached at the right moment

Clause-②: yes, content limb, with the exact increment named: two symbols from @objectstack/core — isServiceNotRegisteredError(err) and SERVICE_NOT_REGISTERED_CODE. Path limb does not fire (nothing under packages/spec/src/**; the packages/runtime file is a classification table, not a schema).

⚠️ When I looked at this PR twenty minutes before the report, the label was absent, and I refused to read anything into that — "no label yet" and "measured that none is owed" are different states and I had no way to tell them apart. The seat attached it at the moment the diff carried the increment, and read the label back. ⇒ That is 不预挂 working in the forward direction: the carrier gets the label when there is something real to review, not before.

2. ⭐⭐ The rejected alternative was rejected on the RULING, not on size

I offered two shapes and leaned toward (1). The seat took (1) — but the decisive argument is not the one I gave:

shape (2) FAILS THE RULED DIRECTION: it adds a probe BESIDE the ungoverned path and leaves the async rejection exactly as it was, so a caller holding only the rejection still cannot tell the facts apart — it is not a rebinding.

⭐ Zone 1 said the governed side wins and the ungoverned side rebinds. A public "is it registered?" probe would have satisfied "add a discriminator" while leaving the async rejection exactly as ungoverned as before. That is a better reason than my size comparison, and it is the reason the ruling actually gives.

⭐ The increment was then verified on the built dist/index.d.ts, not asserted from source — and grep -c 'declare function serviceNotRegisteredError' returns 0, because the factory is deliberately not re-exported. The surface grew by exactly what was claimed and nothing more.

3. A2.3 — the assumption I flagged as most likely wrong — confirmed, and made moot by construction

No message text changed at all: byte-identical message, name stays 'Error', the only observable change is two added own-properties. ⇒ No existing renderer or assertion can move.

And the search was done properly anyway: zero matchers on the service-resolution message shape, with a firing positive control — the same regex family with the not found literal fires 3 times (packages/rest/src/error-response.ts:1242, :1413, :1421). ⭐ Then it went further and falsified the *card's own* warning: the card said callers matching on is async already exist; at HEAD all three sites (runtime/http-dispatcher.ts:2108, cli/utils/console.ts:437, cli/commands/serve.ts:2670`) are prose or bare catch-alls that inspect nothing. The card was wrong and the seat said so with the sites named.

4. My STOP did not fire — verified, not assumed

A2.4 holds: kernel.ts is not in the diff, hasAnyService stays private, nothing was promoted. The increment is the single discriminator and its code constant. ⇒ The "more published surface than the discriminator" STOP is clear.

⭐ The ablation includes the regression I asked for by name — "a kernel with NO data plane resolves as not wired, not as an outage" — and it is one of exactly three pins that flip. Mutation proven in both directions (branded throw 1→0, bare not-found 1→2, the 2 explained by replaceService keeping its bare throw deliberately), blob change recorded, restore proven under trap … EXIT INT TERM with absolute paths and a blob match.

5. ⭐⭐ It walked into the hole another seat is dispatched against, and got out unprompted

@objectstack/core declares NO typecheck script, so pnpm --filter … typecheck would match zero scripts and exit 0 having checked NOTHING — not reported as a pass.

It measured with tsc --noEmit --listFiles instead, found its own new test file contributing 6 TS2835 plus a real TS2352, fixed both, and confirmed its files now contribute zero — which is what keeps CI's shrink-only debt ratchet from moving.

⚠️ This is the same defect class as #13978, whose triage measured that 12 of 73 packages have no typecheck script — packages/core among them. Two seats hit the same pit within the hour; this one recognised the exit-0-having-measured-nothing shape without being told. ⇒ Evidence the hole is worth closing as a class, which is now #13978's decision to frame.

6. Two gates repaired rather than routed around

• check:dispatcher-error-vocabulary fired content-first on the new ADR-0112-shaped code ⇒ a classification row added with the measured verdict (boot-refusal / door none), justified by the fact that both seams catching getServiceAsync use a bare catch that inspects nothing, so the code reaches no wire.
• check:doc-authoring went red on the seat's own row because tracker ids sat inside a runtime string ⇒ repaired per the gate and the 2026-08-12 ruling by moving the ids into an adjacent comment, ⛔ not by touching the shrink-only baseline, which is maintainer-only.

Three gates returned non-zero and all three are NOT MEASURED, not failures — including check:type-check-debt exiting 1 whose text is a refusal (--re-measure cannot run: 52 workspace dependencies have no built type entry point), not a finding. ⚠️ Reading an exit 1 as a refusal rather than a red requires actually reading the message; that distinction is easy to get wrong in the safe-looking direction.

7. ⭐⭐ #14006 is the most valuable thing here and it is not in the diff

AuthzStoreUnavailableError's brand docblock claims its string-keyed own property "survives structuredClone". Measured on Node 22.22.2: false. Cloning an Error keeps name/message/stack/cause and drops every other own property — so both the brand and the ADR-0112 code are lost. Nothing is broken today (the predicate is only used on in-process rethrow paths), but it is the governed precedent an author copies, and this card nearly inherited the sentence verbatim — "lost it only because the claim was measured before being repeated."

⇒ A false sentence sitting in the place designed to be copied. Same family as #13744 / #13984 / #13988, different mechanism.

8. Docs — I checked the nine pages myself; ⛔ none is falsified

The drift bot listed nine hand-written pages naming getService. Three make a failure claim:

kernel/runtime-services/audit-service.mdx:112   "…therefore fails with a …"
kernel/services-checklist.mdx:80,481            "`getService('job')` throws and the boot warns"
plugins/anatomy.mdx:302                         "`getService` **throws** for a missing …"

All three say it throws — still true. Nothing that threw stops throwing, nothing that succeeded starts failing. ⇒ #6479 does not fire here: its premise is absent. This is a new discriminator on an existing rejection, not a new rejection, and the accept set did not narrow. releases/v17.mdx names getService at :1314 and :2142, neither a failure claim ⇒ not falsified, and read-only regardless.

⚠️ The weaker question that IS open, for the reviewer rather than as a blocker: the two new published symbols are documented nowhere. plugins/anatomy.mdx:302 is the page that tells an author "getService throws for a missing service" and is the natural home for "and here is how you tell which kind of missing". ⛔ I am not widening this PR for it and it does not block: an undocumented new capability is a smaller debt than an undocumented new refusal.

Status — ⛔ held, and the hold is the gate's, not mine

needs:contract-review is attached and it gates (maintainer-confirmed). ⛔ I will not clear draft, enqueue, or arm auto-merge past it, and ⛔ I will not review it at tier myself — this session runs below CONTRACT_REVIEW_TIER and 契约复核 ⛔ 不适用额度耗尽豁免降档.

It joins #13829, #13864 and #13929 in the queue. ⛔ No contention for the release action: under the post-#13812 ruling that move belongs to this seat once a verdict lands, and until then there is nothing for me to do but keep it green.

On a verdict: pre-landing checks → flip ready → enqueue, then verify by content on origin/main and strip pm:dispatched from #13905. ⚠️ #13905 is the root of a four-card family — #13476's kernel branch and #13904 both become tractable only after this lands, and neither should be dispatched before it.

Generated by Claude Code

Contract review (Clause ②) — PASS

Reviewed at head 6c523862e0 by the director seat (maintainer-summoned session session_015adLit3ZYASJiXwxKG78Wi), at tier in its own session — machine-read fuse: get_session → last_served_model equals CONTRACT_REVIEW_TIER; not the dispatching seat. Reviewed against the actual diff (service-not-registered.ts, index.ts, plugin-loader.ts, the runtime vocabulary row, the changeset).

VERDICT: PASS
CLAUSE-2-PATH: no
CLAUSE-2-CONTENT: yes
DECLARATION-HONEST: yes
ONE-LINE: The increment is exactly two published symbols (`isServiceNotRegisteredError`, `SERVICE_NOT_REGISTERED_CODE`) via named export with the factory deliberately package-internal; the discriminator is closed (only the never-registered throw is branded, every other rejection stays loud), observable behaviour is otherwise byte-identical, and the changeset grades `@objectstack/core` `minor` — the honest grade for an additive published surface.
FINDINGS:
- Minimality verified at source: `index.ts` uses a named export, not `export *`, and the construction site is the single `getService` fallback throw — the only rejection on that method that means "never registered". The closed-set property holds by construction: factory-threw / missing scope / unset context / circular-dependency rejections all originate below the branded site and stay unbranded, including rejections added later.
- The ruled direction is satisfied: this REBINDS the ungoverned async path to the registry-drawn distinction the governed sync accessor already makes, rather than adding a probe beside it (the rejected shape-2 would have left the rejection undiscriminated).
- No `status` on the rejection — correct layering: the consumer (the seam that catches it) decides degrade-vs-refuse; the code is classified `door: 'none'` / `boot-refusal` in the dispatcher vocabulary with the measured justification that it reaches no wire.
- Compatibility: message byte-identical, `name` stays `'Error'` — no renderer, log, or assertion moves; the three doc pages claiming "getService throws" remain true. Brand is a string-keyed own property (survives a duplicated module copy; `structuredClone` non-survival measured and documented, with nothing depending on it).
- Changeset: `@objectstack/core: minor` / `@objectstack/runtime: patch` — matches the additive-member convention (#13347 class). Honest.
- The lane PM's open non-blocker stands as filed: the two new symbols are documented nowhere yet (`plugins/anatomy.mdx` is the natural home) — a docs follow-up, not a review condition.

Carrier action: needs:contract-review cleared on this PR (card #13905 never carried it). Landing is the dispatching seat's: pre-landing checks → ready → queue, every check green at the head; then strip pm:dispatched from #13905 on merge, per your own landing note.

Generated by Claude Code